Repository navigation
docs(signing): verify against a counterparty's several agents - #1871
Merged
Merged
Conversation
VerifyOptions.agent_url read like an expected-agent check, which led an adopter to model one agent per principal (#1214, prebid/salesagent#2276). It is attribution only: the verifier copies it onto VerifiedSigner and never compares it. Which agent signed follows from the key resolver. Document that on the field, and add a recipe to the request-signing guide for accepting any of a counterparty's agents in one verification: - framework verification maps every agent in one SignerKeyResolver and each agent URL to the same principal; - direct verify_request_signature callers wrap the resolver as the framework does, narrow it to the principal's canonicalized agent set at step 7 (no nonce claimed for a key outside it), and take the agent from the key resolved in that call, never from shared "last matched" state; - the 3.3 path binds each origin to one principal through OriginBindings. The RFC 9421 recipe is marked deprecated: AdCP 3.3 deprecates the profile and 4.0 removes it with brand.json agents[] and jwks_uri (adcontextprotocol/adcp#8664). No API changes. Refs #1214 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
![aao-secretariat[bot]](https://avatars.githubusercontent.com/u/221690821?s=60&v=4){kind=small}
There was a problem hiding this comment.
Ladon verdict: Approve
Approve — docs-only PR plus a 7-line docstring on VerifyOptions.agent_url.
What I checked:
- No findings from the reviewer (no blocking or Medium).
high_riskis true only becausesrc/adcp/signing/verifier.pyis(modified); with zero medium-or-higher findings, the modification is presumed safe (no deletion, no sensitive-category concern).gated_paths: false, no no-auto-approve team match, no prior decision.- Reviewer verified the migration recipe against source:
agent_urlcopied at verifier.py:556 and never compared;jwks_resolverinvoked at step 7 (verifier.py:391) before nonce insert so no nonce burned; dual-kid handling in signer_keys.py; all recipe imports resolve fromadcp.signing.__all__; cross-link anchors exist; test-plan checkboxes checked. docs(signing):prefix is correct — no public-API signature change, just a docstring addition, so no semver/breaking signal required.
Decision table: rows 1–8 do not fire (no critical/high, no medium, gated_paths false, no deletion, no team gate). Falls through to row 9 → approve.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Resolves #1214 with documentation. The SDK can already verify a request against any of a counterparty's agents. What it lacked was a statement that
VerifyOptions.agent_urlis not a check, and a recipe for verifying against several agents.VerifyOptions.agent_urlis attribution only. The verifier copies it ontoVerifiedSigner.agent_url(verifier.py:556) and never compares it with anything, soagent_url=Noneskips no check. Which agent signed follows from the key resolver. The field now says so.docs/request-signing-migration.md: "Verify against a counterparty's several agents".SignerKeyResolver(StaticSignerKeys,JwksUriSignerKeys, from feat(signing): verify request signatures in the framework before dispatch #1266), and map each agent URL to the same principal.verify_request_signaturedirectly: wrap the async resolver as the middleware does. Narrow it at step 7 to the principal's canonicalized agent set; a key outside the set isrequest_signature_key_unknownand claims no nonce. Take the agent from theResolvedSignerKeyresolved in that call. Shared "last matched" state would attribute one request to another request's agent under concurrency.DiscoveredSignerKeysplusOriginBindings(feat(identity): add experimental AdCP 3.3 agent identity #1502). One principal may own several origins.agents[]andjwks_uri(4.0: remove the RFC 9421 brand.json signing profile, brand.json trust fields and identity.brand_json_url adcp#8664).docs/agent-identity-3-3-migration.mdgains a paragraph on binding several origins to one principal, linked both ways.There are no API changes. A
VerifyOptions.acceptable_agent_urlsfield and a multi-agent brand.json resolver were considered and rejected:VerifyRequestOptionshas no expected-agent option; that verifier takesagent_urlfrom the resolver too.Context: prebid/salesagent#2276 and adcp-client-python#1500, which notes it covers #1214 on the 3.3 path.
Test plan
httpx.ASGITransport, withStaticSignerKeysfor three agents across two principals. All checks passed:request_signature_key_unknownfor this principal, and the same request then verifies for its own principal, so no nonce was burned;request_signature_replayed;make lint,make typecheck, black.pytest tests/conformance/signing tests/test_brand_authz.py tests/test_signed_request_verification.py tests/test_docstring_consistency.py: 1921 passed, 2 skipped.Refs #1214
🤖 Generated with Claude Code